home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / doors_2 / wtchdg.zip / READ.ME < prev    next >
Text File  |  1992-07-27  |  12KB  |  293 lines
  1.                               WatchDog v.1.20
  2.                         (c) 1992 Ernest Vogelsinger
  3.  
  4. Package Contents
  5. ----------------
  6.  
  7. The WTCHDG.ZIP archive contains the following files:
  8.    o WATCHDOG.COM    the WatchDog program
  9.    o READ.ME         you're currently reading this file, thank you!
  10.    o FILE_ID.DIZ     description for automatic extraction by BBS'es
  11.    o DESC.SDI        description for automatic extraction by BBS'es
  12.  
  13.  
  14. General
  15. -------
  16.  
  17. WatchDog is a resident utility program monitoring the activity status of
  18. a COM port (carrier) and DOS (Dos and Kbd calls).
  19.  
  20. Its main use is with remote BBS software that hands control to e.g. a
  21. shell program. When the shell program hangs (Dos watch) or carrier loss
  22. is detected (COM watch) the serial port DTR is dropped (hangup) and the
  23. machine is rebooted.
  24.  
  25. VERSION 1.20 - NEW FEATURE
  26. By popular demand, a ring count watch has been added. This is to allow
  27. reboot when the BBS program fails to go off-hook, by what reason ever.
  28. The ring watch can be customized to any needed ring count and can also
  29. be disabled.
  30. After a certain time without a ring indicated by the modem, WatchDog will
  31. assume ringing has stopped, and reset the ring counter. This no-ring time
  32. can also be customized.
  33.  
  34.  
  35. Main features of WatchDog
  36. -------------------------
  37.  
  38.    o Needs only 800 bytes of memory.
  39.    o Can be activated, deactivated, and reconfigured as often as needed,
  40.      and it can also be unloaded.
  41.    o Monitoring is lightning fast so no data loss should occur with
  42.      high speed serial communications.
  43.    o Detects carrier loss by monitoring COM 1, 2, 3 or 4.
  44.      The COM port can be selected from the command line, or carrier monitor
  45.      can be completely switched off.
  46.    o Built-in ring counter to reboot when the BBS fails to go off-hook.
  47.      Reboot counter can freely be specified or disabled.
  48.    o Detects a hanging program by monitoring "DOS" activity.
  49.      WatchDog accepts Int16 (keyboard), Int21 (DOS), and Int28 (DOS Idle)
  50.      as "DOS" activity. The "DOS" timeout seconds can be selected from the
  51.      command line, or "DOS" monitoring can be completely switched off.
  52.    o The reboot method can be selected from "Bios" (the usual jump to
  53.      bios location FFFF:0), and "Hardware", where the CPU is rebooted
  54.      via a command to the keyboard controller. This is often necessary with
  55.      protected mode DOS extenders.
  56.    o Reboot can be delayed to allow lazy write cache programs write their
  57.      data back. The delay time can be selected from the command line.
  58.  
  59. WatchDog can be tailored to meet individual requirements with command line
  60. arguments. It may be executed multiple times, without being reloaded.
  61. A secondary copy always modifies the settings of the resident watchdog.
  62.  
  63.  
  64. WatchDog Command Line
  65. ---------------------
  66.  
  67. You load (and reconfigure) WatchDog by specifying
  68.  
  69.    WATCHDOG [/option=value] ...
  70.  
  71. on the command line, or in a batch file.
  72.  
  73. WatchDog recognizes the following parameters:
  74.  
  75.    /COM=n
  76.       n  - A value between 0 and 4, specifying the COM port to monitor.
  77.            Specifying 0, or a non-existent port, will disable
  78.            carrier monitoring and ring counting.
  79.            NOTE: different to version 1.11, the /COM parameter doesn't
  80.                  enable or disable carrier watch, since the ring count
  81.                  feature has been added. To enable or disable carrier
  82.                  monitoring, use the following parameter.
  83.  
  84. ** 1.20 NEW **
  85.    /CARRIER=ss
  86.       ss - A string specifying carrier monitoring activity. You may specify
  87.            ON  - enable carrier monitor
  88.            OFF - disable arrier monitor
  89.  
  90.    /DOS=nn
  91.       nn - A value between 0 and 65535, specifying the number of seconds
  92.            that DOS may be inactive before WatchDog reboots.
  93.            Specifying 0 will disable DOS monitoring.
  94.  
  95. ** 1.20 NEW **
  96.    /RING=nn
  97.       nn - A value between 0 and 65535, specifying the number of rings that
  98.            will be allowed for rebooting.
  99.            Specifying 0 will disable the ring monitor.
  100.            NOTE: if the modem is online (carrier active), the ring monitor
  101.                  is automatically disabled, regardless of the carrier
  102.                  monitor status.
  103.  
  104. ** 1.20 NEW **
  105.    /NORING=nn
  106.       nn - A value between 0 and 65535. After this time is elapsed without
  107.            a ring to occur, WatchDog determines that ringing has stopped,
  108.            and resets the ring counter.
  109.  
  110.    /MPX=xx
  111.       xx - A (hexadecimal) value between C0 and FF, specifying the ID byte
  112.            for the Multiplexer communication (see note on MPX below).
  113.            The default value is C0, or the first free ID byte found.
  114.  
  115.    /BOOT=ss
  116.       ss - A string specifying the boot method. You may specify
  117.            BIOS     - boot by passing control to the bios location FFFF:0
  118.            HARDWARE - boot by resetting the CPU via keyboard controller
  119.         or HW         (see note on booting below).
  120.  
  121.    /WAIT=nn
  122.       nn - A value between 0 and 65535, specifying the number of seconds
  123.            that WatchDog will wait for DOS to become idle before rebooting
  124.            (see note on delayed boot below).
  125.  
  126.    /DELAY=nn
  127.       nn - A value between 0 and 65535, specifying the number of seconds
  128.            that WatchDog will delay before rebooting (see note on delayed
  129.            boot below).
  130.  
  131.    /WATCH=ss
  132.       ss - A string specifying WatchDog activity. You may specify
  133.            ON  - enable WatchDog
  134.            OFF - disable WatchDog
  135.            This en- and disables the overall WatchDog activity. If either
  136.            carrier detect or DOS monitor is disabled, specifying ON will
  137.            not change these values.
  138.  
  139.    /UNLOAD
  140.            Unloads the resident WatchDog if possible. If another program
  141.            has hooked one of the interrupts WatchDog uses, it will display
  142.            a message and disable itself.
  143.  
  144.    /STATUS
  145.            Displays the current WatchDog status.
  146.  
  147.    /?, /HELP
  148.            Displays a descriptive help text.
  149.  
  150.    /DEFAULT
  151.            Displays the built-in default values.
  152.  
  153.    /QUIET
  154.            Suppresses all output messages.
  155.  
  156.  
  157. The Multiplexer Interface
  158. -------------------------
  159.  
  160. The Multiplexer interrupt (Int2F) is a mechanism for programs to communicate.
  161. WatchDog uses this mechanism to communicate between the transient program
  162. (the loader) and the (smaller) part that stays resident in memory.
  163.  
  164. The defined interface protocol is very simple. An ID byte is specified in
  165. the AH register, and the function code is put in the AL register. Then the
  166. interrupt is called. The ID bytes C0 .. FF are reserved for "user programs".
  167.  
  168. WatchDog tries to find a free ID value between C0 and FF and will use this.
  169. Sometimes it is necessary to avoid certain ID values to allow other programs
  170. that do not scan for a free byte to run. This is the reason why the Mpx ID
  171. can be specified on the command line. Usually you will not need to change
  172. this.
  173.  
  174.  
  175. Booting The Machine
  176. -------------------
  177.  
  178. Generally, there are two ways to reboot a (DOS) computer via software. The
  179. method used most is to pass control to the code at FFFF:0. While this works
  180. in most cases where "DOS only" is loaded, it might cause problems with
  181. certain types of protected mode DOS extender software. The machine might
  182. endlessly hang, and not reboot. One example I personally know is Soft-ICE,
  183. a protected mode debugger software. I have heard rumours that QEMM or EMM386
  184. might react similar in some cases.
  185.  
  186. If you encounter that problem, add /BOOT=HW to the command line to enable
  187. hardware CPU reset.
  188.  
  189. WatchDog resets the CPU by sending a special command to the keyboard
  190. controller. The keyboard controller (port 64h) understands a lot of commands.
  191. The command we need here is Fx, that pulses bits of the output port low
  192. for 6 µs. Bits 0-3 of command indicate which bits should be pulsed:
  193. 0=pulse, 1=don't pulse. Pulsing bit 0 (command FE) results in CPU reset
  194. since it is connected to system reset line.
  195.  
  196. There are some PS/2 computers where this method will not work (I think it's
  197. PS/2 model 80).
  198.  
  199.  
  200. Modem Hang Up
  201. -------------
  202.  
  203. If a COM port is specified, and WatchDog is about to reboot, it drops
  204. the DTR (Data Terminal Ready) and RTS (Ready To Send) lines on the modem,
  205. causing the modem to hang up and the serial port to be reset.
  206. While this might not be necessary with carrier loss, it is a must if reboot
  207. is caused by DOS timeout.
  208.  
  209.  
  210. Delayed Boot
  211. ------------
  212.  
  213. A very special feature is WatchDogs Delayed Boot opportunity.
  214. Whenever you're using a lazy-write cache program (like SMARTDRV etc) you'll
  215. loose data when rebooting, if the cache software couldn't finish writing
  216. your data back.
  217.  
  218. The first thing WatchDog does after resetting the modem is to wait for DOS
  219. to become available. Since the cache software needs DOS to write the data
  220. to disk, it will not do disk writes if DOS is busy. The time how long
  221. WatchDog should wait for DOS to become available is specified with the
  222. /WAIT=nn command line parameter.
  223.  
  224. After DOS is available, WatchDog waits for the time specified in the
  225. /DELAY=nn parameter. While waiting, it repeatedly issues Int28, thus
  226. pretending that DOS is idle on the command line.
  227.  
  228. Both actions together (wait for DOS to become available, and then loop for
  229. a couple of seconds) allows lazy write caches to finish their write activity.
  230.  
  231. However, if DOS will not become available (e.g. if some DOS structure has
  232. been corrupted, and DOS itself is hanging), WatchDog will reboot the machine
  233. without being able to give time to background programs. In these cases,
  234. data loss will occur and cannot be avoided.
  235.  
  236.  
  237. The Legal Department
  238. --------------------
  239.  
  240. Users of WatchDog must accept the following disclaimer of warranty:
  241.  
  242. THIS COPYRIGHTED SOFTWARE AND ITS DOCUMENTATION IS PROVIDED ON AN "AS IS"
  243. BASIS. THE AUTHOR MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED,
  244. INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR
  245. FITNESS FOR A PARTICULAR PURPOSE.
  246.  
  247. THE USER ASSUMES ALL RISKS OF THE USE OF THIS SOFTWARE. THE AUTHOR ASSUMES
  248. NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE
  249. USE OR MISUSE OF WATCHDOG.
  250.  
  251. As it cannot be guaranteed that loss of data will not occur, WatchDog should
  252. be tested with non-critical data. As always, judicious backups are a wise
  253. and necessary continuing precaution.
  254.  
  255.  
  256. Zero-Registration Shareware, Distribution Policy
  257. ------------------------------------------------
  258.  
  259. Now that the necessary legal issues are out of the way:
  260.  
  261. WatchDog is a program I wrote because I was missing a lot of features in
  262. the watchdog program I have got (it was written in '84, and therefore
  263. heavily aged out).
  264.  
  265. WatchDog v.1.20 is "zero-registration" shareware. that means, you may use it
  266. freely, without notifying me or anyone else, and without paying one cent. I
  267. sincerely hope it will satisfy you.
  268.  
  269. You may freely distribute WatchDog, as long as the archive file remains
  270. unmodified. I expressly forbid to add any files, or any comments to the
  271. archive.
  272.  
  273.  
  274. WatchDog Source Code
  275. --------------------
  276.  
  277. The source code for WatchDog can be obtained by contacting me at the
  278. CompuServe address mentioned below. The fee for the source code is
  279. US$ 150.--. For more information, please contact me.
  280.  
  281.  
  282. Contacting The Author
  283. ---------------------
  284.  
  285. If you have questions or ideas for future enhancements of WatchDog, I'd be
  286. glad if you would contact me via CompuServe. Of course, I'll be happy if you
  287. just want to tell me the program works well.
  288.  
  289.    Ernest Vogelsinger
  290.    CIS 100015,551
  291.  
  292. (Thank you for reading the complete file!)
  293.